home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / BARNET / FREENET / SKELTON / SMTPD / SMTP / Help! < prev    next >
Text File  |  1995-11-17  |  9KB  |  185 lines
  1. User Documentation for Ant's RISC OS SMTP Daemon version 0.10
  2. =============================================================
  3.  
  4. Requirements
  5. ------------
  6.  
  7. You will require a working TCP/IP stack (eg Acorn's !TCPIP or FreeNet) to use this module,
  8. and also the 'InetDB' module which is distributed with FreeNet.
  9.  
  10. Intro
  11. -----
  12.  
  13. 'smtpd' is a RISC OS module which provides a number of the features commonly found in SMTP
  14. daemons on other, larger computers. Chief among these is the ability to accept connections
  15. from other SMTP daemons, and process mail to multiple users at the local site. Also significant
  16. is the fact that the module does all this in the background, regardless of whether the machine
  17. is in the desktop or not.
  18.  
  19. 'smtpd' broadly conforms to the 'minimal implementation' defined in RFC 821, and also adheres rather
  20. strictly to the buffer length limits specified therein. Allegedly, this minimal installation has
  21. been superceeded by a later RFC, so I might conform to this in a later version, once I've finished
  22. arguing about it with Stewart. :) 'smtpd' is intended for receiving mail
  23. only, ie it expects to be the last host in any given forward path. 'smtpd' does not currently
  24. allow the sending of mail to other hosts, nor does it implement mail forwarding. Currently, 'smtpd'
  25. will allow only 1 connection from a remote host at a time, which isn't envisioned as being a 
  26. problem. This can be bumped up in a later release if necessary.
  27.  
  28. Optionally, 'smtpd' will provide basic logging and host authentication services.
  29.  
  30. The rationale for the strict buffer length limits, and the provision of only a single connection
  31. at a time, is that I want to keep the memory and performance hits for this module as low as possible.
  32.  
  33. Commands & Responses
  34. --------------------
  35.  
  36. 'smtpd' responds to the following RFC 821 commands: HELO, MAIL, RCPT, DATA, RSET, QUIT, NOOP, EXPN
  37. and HELP. It does not respond to VRFY, SEND, SAML, SOML, or TURN. 'smtpd' will return standard
  38. responses for these commands, and for any other input it will return '500 Syntax error, command not
  39. recognized'. 
  40.  
  41. After rereading the RFC, I've a feeling that EXPN may actually be  doing VRFY's job, so the supported
  42. commands may change in a future release. SOML will probably be supported in the next release, and the
  43. remaining commands will follow in the full implementation (send as well as receive mail).
  44.  
  45.  
  46. Environment
  47. -----------
  48.  
  49. 'smtpd' requires a number of files to work correctly. It expects to find these files in the directory
  50. specified by the environment variable <SMTPConfig$Dir>. Currently 'smtpd' expects to find the file
  51. 'users' in this directory, and depending on the command line options it may also want to read 'hosts'
  52. and write to 'logfile' in the directory.
  53.  
  54. Command line arguments
  55. ----------------------
  56.  
  57. Typically, 'smtpd' is invoked via the command line,
  58.  
  59.     RMLoad smtpd [options]
  60.     
  61. where [options] consists of any of the following (order or case are irrelevant):
  62.  
  63.     -port <n>       set the port number smtpd listens on to 'n' (default = 25)
  64.     -host <string>     sets hostname to <string>. By default smtpd will work this out for itself.
  65.     -hostname <string> same as above
  66.     -quiet               causes smtpd to generate as little output as possible.
  67.                Errors are still reported. (disabled by default).
  68.     -silent           same as above
  69.     -secure           causes smtpd to run in 'secure' mode (see below). (disabled by default).
  70.     -logfile       causes smtpd to keep a log of events in <SMTPConfig$Dir>.logfile
  71.                (disabled by default).
  72.                
  73. If no options are specified, smtpd defaults to -port 25 -host <Inet$HostName>.
  74.                
  75. The 'users' file
  76. ----------------
  77.  
  78. The file "<SMTPConfig$Dir>.users" tells smtpd what to do with mail for a specific user. If smtpd receives
  79. a request for a user who's name is not in this file, the request will be denied.
  80. This file consists of lines, which may be one of three forms. They are either:
  81.  
  82.     1) a comment line - any line which starts with a # is ignored
  83.     2) a mailbox line - tells smtpd where to put the mail for a given user
  84.      or 3) an alias line  - tells smtpd what other names a user is known by.
  85.      
  86. Mailbox lines have the format "<username> <real name> <mailbox path>" where <username> specifies a valid
  87. recipient at the local address, and <mailbox path> specifies the full pathname of a file in which
  88. to store mail for that user. If the file doesn't exist, smtpd will attempt to create it. If it does
  89. exist, smtpd will append new mail to the end of it (ie the old contents will be preserved.)
  90. The <real name> parameter should be the user's real full name. If this parameter is to include spaces, it
  91. must be enclosed in quotes to protect it from the parsing process. For example these are valid config lines:
  92.  
  93.     ant    "Ant Skelton"    <MailOut$Dir>.AntMail
  94. or    ant    Skelton        <MailOut$Dir>.AntMail
  95.  
  96. whereas this is _not_ a valid config line:
  97.  
  98.     ant     Ant Skelton    <MailOut$Dir>.AntMail
  99.     
  100. if this line were used in an smtp config file, smtp would assume that user 'ant' has a real name 'Ant' and
  101. that his mail is to be saved in 'Skelton' - ie a file called 'Skelton' off the root directory of your 
  102. primary hard-disc. You'll probably agree that this isn't a very desirable state of affairs, so cock-ups of
  103. this nature are best avoided.    
  104.  
  105. Alias lines have the format "<username> alias <realusername>". Any mail arriving addressed to <username>
  106. will be stored in the mailbox for user <realusername>. Note that literal 'alias'. It's not in upper- or
  107. mixed-case, it's in lower-case. smtpd won't like it if you use upper- or mixed-case. And who can blame it?
  108.  
  109. When smtpd starts, it loads and parses the 'users' file. If there are any errors or discrepancies in the
  110. file then smtpd will complain and fail to start. An example file is provided.
  111.  
  112. smtpd allows you to use aliases for other aliases as many levels deep as you like, provided that an
  113. actual mailbox emerges at the end of it. Avoid circular references in alias files, as smtpd will become
  114. confused, and probably fall over. As smtpd is by this stage hooked in to a handfull of your more
  115. important vectors, you probably want to avoid this scenario.
  116.  
  117.  
  118. Secure operation
  119. ----------------
  120.  
  121. Specifying the -secure switch when running smtpd causes it to implement a very basic level of remote
  122. host authentication. When running in secure mode, smtpd will only accept connections from machines
  123. who's IP addresses are in the file "<SMTPConfig$Dir>.hosts". Lines in this file are either comment
  124. lines (as for the "users" file) or consist of:
  125.  
  126.     <hostname>    <numeric IP address>
  127.     
  128. where <hostname> is a human-readable string, eg 'groovy.org' and <numeric IP address> is the host's
  129. IP address, in 'dot notation' eg "136.170.135.98". An example file is provided.    
  130.  
  131. When a remote machine attempts to connect to smtpd, the module will look it up in its trusted host
  132. database, and if the host isn't recognized the connection will be rejected. (The remote client will
  133. receive the response '421 Service not available', so it won't know that it's been rejected on security
  134. grounds: it only knows that smtpd was unable to talk to it.)
  135.  
  136. Authentication is done on the numeric IP addresses, as these are slightly harder to forge than human-
  137. readable host names (but realise that they're both pretty easy to forge.) If a trusted host is recognised, 
  138. the <hostname> entry from the 'hosts' file is used. In non-secure mode, a DNS lookup is performed.
  139.  
  140. ** NB **
  141. Note that this is fairly primitive security - if you're paranoid about who can connect to your
  142. machine, you're better off not using this module at all. It's mainly intended for use if you'll 
  143. typically only be receiving mail from one site - eg via a dial-up to an internet provider.
  144.  
  145. Logging
  146. -------
  147.  
  148. Specifying the -log switch when running smtpd causes it to log pertinent information to the file
  149. <SMTPConfig$Dir>.logfile. smtpd logs all connections and mail transfers. In secure mode, smtpd 
  150. will also log failed connections.
  151.  
  152. Star Commands
  153. ---- --------
  154.  
  155. When all's said and done, smtpd is a module, so I couldn't leave you without some * commands to
  156. play with. The following commands are available:
  157.  
  158.     *smtpusers    print information on smtp's user database. Includes alias info.
  159.     
  160.     *smtpstats    prints information on smtp's internal states. The amount of information
  161.             presented by this command varies depending on what smtpd is doing at the
  162.             time.
  163.             
  164.     *smtpclose    causes an open connection to be terminated, and all state variables are
  165.             reset, files closed, etc. Useful as a last ditch measure if smtpd has
  166.             jammed and isn't accepting connections. Note that the data in the logfile
  167.             may not necessarily be correct if this command is used.
  168.                         
  169. History
  170. -------
  171.  
  172. smtpd began life as a warm-up exercise in preparation for writing an http server, but due to the recent
  173. population explosion in http servers, I've decided to refine smtpd a bit, and move on to other things.
  174. smtpd has also been prodded along by Dave Walker (who has done an inordinate amount of testing) and
  175. Graham Allan (who wanted an alternative to the NFS mail fetch in the TCPIPtransport module I provide
  176. for NewsBase.) Special mention must also go to siplus@bigblue.demon.co.uk, who ruthlessly persued the
  177. RSET bug. Thanks guys! 
  178.  
  179. Ant.
  180. ----
  181. 1/6/95, 15/6/95, 20/6/95, 15/11/95, 16/11/95.
  182. <ant@eerie.demon.co.uk>
  183.  
  184.  
  185.